Compile-time dependency

To use Errai's data binding module, you must include it on the compile-time classpath. If you are using Maven for your build, add this dependency:

    <dependency>
      <groupId>org.jboss.errai</groupId>
      <artifactId>errai-data-binding</artifactId>
      <version>${errai.version}</version>
    </dependency>

If you are not using Maven for dependency management, add errai-data-binding-version.jar to your classpath.

GWT module descriptor

You must also inherit the Errai data binding module by adding the following line to your GWT module descriptor (gwt.xml).

<inherits name="org.jboss.errai.databinding.DataBinding" />

Bindable Objects

Objects that should participate in data bindings have to be marked as @Bindable and must follow Java bean conventions. All editable properties of these objects are then bindable to UI widgets.

@Bindable
public class Customer {
  ...
  private String name;

  public String getName() {
    return name;
  }

  public void setName(String name) {
    this.name = name;
  }
  ...
}

Initializing a DataBinder

An instance of DataBinder is required to create bindings. It can either be

injected into a client-side bean:

public class CustomerView {
  @Inject
  private DataBinder<Customer> dataBinder;
}

or created manually:

DataBinder<Customer> dataBinder = DataBinder.forType(Customer.class);

In both cases above, the DataBinder instance is associated with a new instance of the model (e.g. a new Customer object). A DataBinder can also be associated with an already existing object:

DataBinder<Customer> dataBinder = DataBinder.forModel(existingCustomerObject);

In case there is existing state in either the model object or the UI components before the they are bound, initial state synchronization can be carried out to align the model and the corresponding UI fields.

For using the model object's state to set the initial values in the UI:

DataBinder<Customer> dataBinder = DataBinder.forModel(existingCustomerObject, InitialState.FROM_MODEL);

For using the UI values to set the initial state in the model object:

DataBinder<Customer> dataBinder = DataBinder.forModel(existingCustomerObject, InitialState.FROM_UI);

Registering a global default converter

@DefaultConverter
public class MyCustomDateConverter implements Converter<Date, String> {

  private static final String DATE_FORMAT = "YY_DD_MM";

  @Override
  public Date toModelValue(String widgetValue) {
    return DateTimeFormat.getFormat(DATE_FORMAT).parse(widgetValue);
  }

  @Override
  public String toWidgetValue(Date modelValue) {
    return DateTimeFormat.getFormat(DATE_FORMAT).format((Date) modelValue);
  }
}

All converters annotated with @DefaultConverter will be registered as global defaults calling Convert.registerDefaultConverter(). Note that the Converter interface specifies two type parameters. The first one represents the type of the model field, the second one the type held by the widget (e.g. String for widgets implementing HasValue<String>). These default converters will be used for all bindings with matching model and widget types.

Providing a binding-specific converter

Alternatively, converter instances can be passed to the dataBinder.bind() calls.

dataBinder.bind(textBox, "name", customConverter);

Converters specified on the binding level take precedence over global default converters with matching types.

Default, Simple, and Chained Property Bindings

By default, bindings are determined by matching field names to property names on the model object. In the examples above, the field name was automatically bound to the JavaBeans property name of the model (user object). If the field name does not match the model property name, you can use the property attribute of the @Bound annotation to specify the name of the property. The property can be a simple name (for example, "name") or a property chain (for example, user.address.streetName). When binding to a property chain, all properties but the last in the chain must refer to @Bindable values.

The following example illustrates all three scenarios:

@Bindable
public class Address {
  private String line1;
  private String line2;
  private String city;
  private String stateProv;
  private String country;

  // getters and setters
}

@Bindable
public class User {
  private String name;
  private String password;
  private Date dob;
  private Address address;
  private List<Role> roles;

  // getters and setters
}

@Templated
public class UserWidget {
  @Inject @AutoBound DataBinder<User> user;
  @Inject @Bound TextBox name;
  @Inject @Bound("dob") DatePicker dateOfBirth;
  @Inject @Bound("address.city") TextBox city;
}

In UserWidget above, the name text box is bound to user.name using the default name matching; the dateOfBirth date picker is bound to user.dob using a simple property name mapping; finally, the city text box is bound to user.address.city using a property chain. Note that the Address class is required to be @Bindable in this case.

Data Converters

The @Bound annotation further allows to specify a converter to use for the binding (see Specifying Converters for details). This is how a binding specific converter can be specified on a data field:

@Inject
@Bound(converter=MyDateConverter.class)
@DataField
private TextBox date;

Replacing a model object

The injected model objects in the examples above are always proxies to the actual model since method invocations on these objects need to trigger additional logic for updating the UI. Special care needs to be taken in case a model object should be replaced.

When working with an @AutoBound DataBinder, simply calling setModel() on the DataBinder will be enough to replace the underlying model instance. However, when working with @Model the instance cannot be replaced directly. Errai provides a special method level annotation @ModelSetter that will allow replacing the model instance. Here's an example:

@Dependent
public class CustomerView {
  @Inject @Model
  private Customer customer;

  @Inject @Bound
  private TextBox name;

  @Bound
  private Label id = new Label();

  @ModelSetter
  public void setModel(Customer customer) {
    this.customer = customer;
  }
}

The @ModelSetter method is required to have a single parameter. The parameter type needs to correspond to the type of the managed model.

Excluding Classes from Validation

By default, Errai scans the entire classpath for classes with constraints. But sometimes it is necessary or desirable to exclude some shared classes from being validated on the client side. This can be done by adding a list of classes and package masks to the ErraiApp.properties file like so:

# The following blacklists the class some.fully.qualified.ClassName and all classes in some.package.mask (and subpackages thereof).
errai.validation.blacklist = some.fully.qualified.ClassName \
                             some.package.mask.*